Assurance API

This page describes how different parts of the Assurance API operate, and how each part can be used.

For more information, refer to the RAML in Anypoint.

Overview

The Assurance API provides end-to-end fault diagnosis and problem management. This API calls all available details of your product instance up front to drive the workflow including service validation, fault diagnostics, outage correlation, and a process for booking appointments and submitting and updating problem reports.

In this section, learn about how to:

• Manage Subscriptions and Notifications
• Use Get Products
• Update WAN Configuration
• Run Diagnostics
• Log a Problem Report
• Book an Appointment
• Manage Problem Reports
• Query Problem Reports

Manage Subscriptions and Notifications

The Assurance API includes the ability to set up subscriptions to be notified with updates to problem reports and events. A subscription URL is provided, or you can specify a target URL for delivery of notifications.

Subscriptions can be updated, deactivated or deleted.

Note: It is not possible to subscribe to receive notifications via webhooks and email at the same time.

Because of the asynchronous nature of problem report updates and status changes it may be helpful to subscribe to a notification instead of polling for updates.

There are three parts to this process:

1. Submit a subscription request - POST /subscribers with a secret key and a destination URL, that is to be used to receive notifications.
2. Validate the webhook endpoint - API Support will work with you to ensure that you are receiving notifications correctly.
3. Manage subscriptions - List, update, deactivate, or delete your subscriptions.

Submit a subscription request

POST /subscriptions

The Assurance API exposes an endpoint (POST /subscriptions) to enable RSPs to subscribe for outbound notifications from Assurance on specified channels. The subscribing party uses the client authentication credentials supplied by Chorus using Basic Authentication.

The following table describes the attributes required to subscribe to a channel for notifications:

Validate the webhook endpoint

Once you post a submission request, our internal processes make the configuration changes. API Support will set up a time with you to test that you are receiving the updates correctly.

Note: Currently this is not an automated process.

Manage subscriptions

GET /subscriptions
GET /subscriptions/{subscriptionid}
PUT /subscriptions/{subscriptionid}
DELETE /subscriptions/{subscriptionid}
POST /subscriptions/{subscriptionid}/deactivate

Once a subscription has been created, you can manage it using the Update, Delete, and Deactivate functions.

The subscription functions are described in the following table:

Notification types

The following table lists the properties present in all notification types across all channels:

ProblemReportNotification

The ProblemReportNotification object is used to send a status change update notifications. Typical use cases are event-based handling of Problem Report changes.

The following table lists the properties of a ProblemReportNotification object:

See the ProblemReportNotification payload property in the API Specification for further details.

DiagnosticSessionNotification

The DiagnosticSessionNotification object contains the details of a diagnostic session.

The following table lists the properties of a DiagnosticSession object:

See the DiagnosticSessionNotification payload property in the API Specification for further details.

 

Use Get Products

GET /products/{productid}

The Get Product API call returns product information.

Get Product queries Chorus inventories including the Chorus address database, product inventories, and problem reports to retrieve all available information for the Product Identifier supplied. The response depends on the type of product, and whether Chorus holds full inventory.

Note: For more information about the different product types, see also Product Details.

The steps required to retrieve product information are described in the following table:

Step	Role	Action	Description
1.	API Consumer	Get Product	Call Assurance API `GET /products/{productid}` method using a Chorus product identifier.
2.	Assurance API	Validate Service	The API validates the service including if the service is active and if it is owned by the initiating RSP (or sub-entity). If the service is inactive, then an API error response is returned. If the requestor is not authorised to access the information, then an API error response is returned. If the API consumer has entered an invalid identifier, then an API error response is returned.
3.	Assurance API	Query inventory	The API queries inventory for Product Service Details. If the product is validated, then where we hold full details of your product instance in our inventory, all information is returned. If the product is partially validated, then where we hold partial details of your product instance in our inventory, the information we have available is returned. If the product is unvalidated, then where the product type is unavailable in our inventory and we are unable to validate the product, the Product Types Possible list is also returned. Details include: A message describing the unvalidated product Available Product Types for the supplied Product Id which can be used for subsequent diagnostics and problem report submission Product Category Type – Generalised product categorisation used for grouping.
4.	Assurance API	Query inventory	The API returns details applicable to the type of service: Product type API also returns Copper DSLAM information Port information Fibre OLT and ONT objects Fibre voice services Plan objects Complex Access type Exchange ID Glass mode Wire Mode RGW Wi-Fi service details
5.	Assurance API	Query address / orders / problem reports	The API queries other inventories to return additional information available for the product instance to support fault diagnosis and resolution. Address details Supported test types Open orders Problem Reports (the last 3 months’ worth).

Update WAN Configuration

PUT /products/{productid}/wan

Note: WAN configuration is only relevant when mode is "RGW".

RGW ONT can be configured and managed by using the ‘Remote Managed Service’ (RMS) Configuration website and in the Assurance API you are able to update the WAN configuration.

For more detailed information on how RMS works please refer to its dedicated webpage here.

When updating WAN configuration, note the following regarding the optional ipMode parameter:

• GET /products/{productid}/wan response may or may not include the optional ipMode parameter.
• If the parameter is included, and the value is 1, then the IP mode is IPV4 only and the IPV4 attributes are returned.
• If the parameter is included, and the value is 3, then the IP mode includes IPV4 and IPV6. Attributes are returned for both.
• If the parameter is NOT included, the device is assumed to be IPV4 and IPV4 attributes are returned.

When updating the WAN configuration using PUT /products/{productid}/wan, note the following:

• If the ipMode parameter was NOT present in the GET call then it MUST NOT be included in the PUT call. As ipV4 mode is assumed the ipV4 object MUST be present in the PUT call.
• If the ipMode parameter was present in the GET call, then ipMode parameter MUST be present in the PUT call. If new value is 1 or 3 , then the ipV4 object MUST be included, If the new value is 3, then the ipV6 object MUST also be included.

Run Diagnostics

POST /sessions

The POST /sessions API call enables the initiation of a diagnostic session. The Assurance API runs the default test(s) and returns results applicable to the product type submitted, where available.

Where a product is unvalidated, the product type must be specified when posting a diagnostic.

Where no default test exists for the product type, then other factors such as any open problems are used to diagnose the fault.

Because of the asynchronous nature of the diagnostics, the time it takes to run a diagnostic depends on two factors:

1. Time for the Diagnostic API to respond. The Diagnostic API should respond within 4-10 seconds.

2. Time for the actual test to complete running. This time depends on the type of test. Indicative average times for each test are:

   • ONT Status, 10 seconds or less
   • Single Line Test, 32 seconds or less
   • Line State Diagnosis, takes 15 seconds or less
   • Electrical Test, 50 seconds or less
   • Wi-Fi information, 30 seconds or less.

Based on these average response times, polling for a result should be set at a frequency of no less than 10 second intervals or alternatively subscribe to be notified when the diagnostic results are ready. See Manage Subscriptions and Notifications.

• Diagnostics sessions timeout after one hour of update inactivity on the session.
• It is possible to cancel a diagnostic using the Cancel Diagnosis API call. This call should only be used if incorrect information such as an incorrect product type has been submitted when posting the diagnostic.
• A diagnostic session concludes with the return of a fault type and associated next steps that can be used in the submission of a problem report.

The table below describes the diagnostic process:

Step	Role	Action	Description
1.	API Consumer	Submit a diagnostic request / Post Diagnosis (Initiate Diagnostics Session)	The Post Diagnosis API call / request initiates default diagnosis action for the product type. For unvalidated services, the product type is required in the request.
2.	Assurance API	Return diagnostic	The Assurance API returns: Diagnostic session identifier Product Service details Actions Fault Types Questions.
3.	Assurance API	Run diagnostic	The Assurance API runs the default test applicable to the product type submitted and query open problem reports, to assist with fault diagnosis. Note: Diagnostics sessions timeout after one hour of update inactivity on the session.
4.	API Consumer	Retrieve a diagnostic	Use the diagnostic session identifier to retrieve the results of a diagnostic.
5.	API Consumer	Determine next step	The API consumer determines and decides the next step. If diagnostics has identified a fault then use the fault type to begin problem report submission. If a problem is already open for the product instance then manage the open problem report.

Log a Problem Report

POST /sessions/{sessionid}/problemReport

The POST /sessions/{sessionid}/problemReport API call enables an API consumer to submit a problem report into the Chorus ITSM tool.

Note: Diagnostics must be completed before submitting a problem report and submitting a problem report triggers the completion of the diagnostic session.

Problem report submission includes completing appointment details where required, and answering standard questions. Non-standard questions also need to be supplied in a problem report submission to ensure Chorus has all supporting information to aid the resolution process.

The table below describes the problem report logging process:

Book Appointment

GET /sessions/{sessionid}/schedule
POST /sessions/{sessionid}/reservations

The GET /sessions/{sessionid}/schedule call queries the Chorus workforce management source to return details of available appointments for products / fault types that require a booking with a service company technician.

Appointment availability is based on the SLAs associated with the product and fault type, and the availability of technicians with the required skill set.

The two booking types are described in the table below:

Type	Description
Confirmed appointment (look and book)	The look and book confirmed appointments are only available for layer 1 UCLL products including SLES, SLU MPF and UCLL MPF. Confirmed appointments use the enumeration BET.
ASAP	ASAP (earliest available appointment) is available for all products. If no appointment type is specified, the ASAP slot is automatically assigned. ASAP is the only option available for layer 1 non-UCLL products. For layer 1 ASAP appointments, use the enumeration BY For layer 2 ASAP appointments, use the enumeration ASAP.

The table below describes the process for booking an appointment:

Manage Problem Reports

POST /problemReports/{problemnumber}/update
PUT /problemReports/{problemnumber}
POST /problemReports/{problemnumber}/close
POST /problemReports/{problemnumber}/cancel

Once a problem report has been logged with Chorus, you can manage the problem using the Update, Amend, Close and Cancel functions.

Note: Problem Report payloads vary between products.

The Problem Report functions are described in the following table:

Query Problem Reports

GET /problemReports

The GET /problemReports call queries for up to 12 months of historical problem reports, and return results based on selected input criteria.

For each field, you can specify a sort order, ascending or descending. Results are paginated with a maximum of 50 records per page.

View Event Notifications

GET /events/{event_id}
GET /events/{event_id}/impact

You can view event notifications for all planned and unplanned Chorus network events, for all of your Chorus services.

The objects returned for events and the information returned are described in the following table.